% tidegauge_README.m
%
% Some notes about various files related to tide gauge records.  Processed
% tide gauge observations in .mat file formats in subfolders located at:
%   /tools_data/obs_data/tide_gauge/Canada/
%   /tools_data/obs_data/tide_gauge/NOAA/
% 
%
% Below is a short list of some basic things you may want to do followed by
% the scripts to use to achieve those things:
%
% YOU WANT TO:
%  - Extract the equivalent of tide gauge records from ROMS history files
%    (you need to do this before you can compare to observations) 
% USE:  ROMS_tidegauge_extractor.m
%
%
% YOU WANT TO:
%  - Compare tidal properties (e.g., amplitude and phase of the M2
%    constituent) from your ROMS run with observations
% USE:  compare_obsROMS_tides.m      (no plots, just prints some stats)
%      or...
%       plot_compare_obsROMS_tides.m (includes stats and plots)
%
%
% YOU WANT TO:
%  - Compare low-pass filtered sea-level from your ROMS run with
%    observations
% USE:  compare_obsROMS_tides.m      (an internal switch allows for simple
%                                     low-pass filtered time series plots)
%
%
% 
% *** GLOSSARY OF TIDEGAUGE FILENAMES WITH SHORT DESCRIPTIONS ***
%
% 0)  tidegauge_README.m
%      path:  /tools/validation_tools/tide_gauge/
%      
%      The file you're reading now!
% 
%
% 1)  ROMS_tidegauge_extractor.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      A driver calling Z_get_tidegauge.m to extract tide gauge records
%      from a ROMS simulation.
% 
%
% 2)  Z_get_tidegauge.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      A copy of Z_get_moor.m to extract tide gauge records from a ROMS
%      simulation (but fewer variables are extracted).  Called by the
%      driver ROMS_tidegauge_extractor.m
%
%
% 3)  tidegaugeLocations.mat
%      path:  /tools/validation_tools/tide_gauge/
%
%      A .mat file containing the data structure 'tgauge' housing the
%      names, station IDs, and positions of various tide gauges of
%      interest.  Can be regenerated or updated using 
%      make_tidegaugeLocations.m
%
%
% 4)  make_tidegaugeLocations.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      A script to generate or update the tidegaugeLocations.mat file.  The
%      user specifies a list of station names.  Calls are made to functions
%      tidegauge_name2id.m and Z_tidegaugeLocations.m to get station ID and
%      position (lon, lat) information for each station.
%
%
% 5)  Z_tidegaugeLocations.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      A function storing position information for various tide gauge
%      stations.  Currently set up for stations within the Cascadia model
%      grid (includes stations in the Salish Sea and along coast from
%      Tofino, BC, south to Charleston, OR).  User can pass in a tide gauge
%      station name and the function will return the position (lon, lat) of
%      that station.
%
%
% 6)  tidegauge_id2name.m
%      path:  /tools/validation_tools/tide_gauge/
%     
%      A function to provide the name of a tide gauge station given its
%      official station ID number (US NOAA or Canada).  Currently set up
%      for most US west coast station from Tofino, BC, to San Diego, CA,
%      including stations in the Salish Sea.
%
%
% 7)  tidegauge_name2id.m
%      path:  /tools/validation_tools/tide_gauge/
%      
%      A function to provide the official station ID number of a tide gauge
%      station given the station name (US NOAA or Canada).  Currently set
%      up for most US west coast station from Tofino, BC, to San Diego, CA,
%      including stations in the Salish Sea.
%     
%     
% 8)  compare_obsROMS_tides.m
%      path:  /tools/validation_tools/tide_gauge/
%      
%      Performs a tidal analysis (using the T_Tide package) for specified
%      tidal constituents of both ROMS and observational tide gauge
%      records.  Skill scores and Willmott skill scores of the hourly
%      sea-level records are also made and printed to the screen.
%
%      
% 9)  plot_compare_obsROMS_tides.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      Calls compare_obsROMS_tides.m to perform a tidal analysis and
%      compute comparison statistics.  Plots maps of tide gauge locations,
%      bar graphs comparing tidal amplitudes and phases (model vs. obs),
%      and line plots of tidal amplitudes and phases as a function of
%      distance into the Salish Sea.
%
%
% 10) InverseBarometerCorrection.m
%      path:  /tools/validation_tools/tide_gauge/
%
%      A function from S. Giddings to make an APPROXIMATE correction for
%      the inverse barometer effect to tide gauge observations.  This is
%      on the to-do list for updating!  Called by compare_obsROMS_tides.m
%      and plot_compare_obsROMS_tides.m
%
%
% 11) make_coastSalish_tide_track.m
%      path:  /tools/validation_tools/tide_gauge/
%      
%      A simple script to make a track from Charleston, OR, into Puget
%      Sound and the Strait of Georgia.  Saves the track components into
%      coastSalish_tide_track.mat.
%
%
% 12) coastSalish_tide_track.mat
%      path:  /tools/validation_tools/tide_gauge/
%
%      A .mat file housing variables 'track_PS' and 'track_SG', lat/lon
%      pairs of tracks from the outer coast to within Puget Sound and the
%      Strait of Georgia, respectively.
%
%
% R. McCabe 06/2014

